home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Magazine / Online / OpenURL / Developer / Autodocs / openurl.doc
Text File  |  1999-09-26  |  8KB  |  270 lines
  1. TABLE OF CONTENTS
  2.  
  3. openurl.library/--background--
  4. openurl.library/--rexxhost--
  5. openurl.library/URL_OpenA
  6. openurl.library/URL_GetPrefs
  7. openurl.library/URL_FreePrefs
  8. openurl.library/URL_SetPrefs
  9. openurl.library/URL_GetDefaultPrefs
  10. openurl.library/URL_LaunchPrefsApp
  11. openurl.library/--background--           openurl.library/--background--
  12.  
  13.     PURPOSE
  14.         The openurl.library provides a means whereby developers
  15.         can easily add "send URL to browser" functionality their 
  16.         applications.
  17.  
  18.         Users may configure their preferred browser(s) through the
  19.         preference program.
  20.  
  21.         To utilise the library, you only need the URL_Open() call. All 
  22.         other functioncalls are only useful if you're making a 
  23.         preferences program.
  24.  
  25.         If you want to program your own preferences program, read this
  26.         documentation and study the included source to the MUI
  27.         preference program.  If you have any questions, contact me.
  28.  
  29.         Troels Walsted Hansen
  30.            troels@thule.no
  31.         Ultima Thule Software
  32.  
  33. openurl.library/--rexxhost--           openurl.library/--rexxhost--
  34.  
  35.     HOST INTERFACE
  36.         openurl.library provides an ARexx function host interface that
  37.         enables ARexx programs to use it. The functions provided by the 
  38.         interface are directly related to the functions described herein, 
  39.         with the differences mostly being in the way they are called.
  40.  
  41.         The function host library vector is located at offset -66 from
  42.         the library. This is the value you provide to ARexx in the
  43.         AddLib() function call. Note that this is different from the 
  44.         usual -30 offset of other libraries! Also, be sure to ask for 
  45.         version 3 of the library when you AddLib() it. See below for
  46.         an example of how to use it properly.
  47.  
  48.     FUNCTIONS
  49.         success = OPENURLPREFS()
  50.  
  51.         success = OPENURL(URL/A,SHOW/S,NOSHOW/S,TOFRONT/S,NOTOFRONT/S,NEWWIN/S,
  52.                           NONEWWIN/S,LAUNCH/S,NOLAUNCH/S)
  53.  
  54.     EXAMPLE
  55.         /* OpenURL.rexx */
  56.         PARSE ARG url
  57.         OPTIONS RESULTS
  58.  
  59.         /* Load the openurl.library as a function host */
  60.         IF ~SHOW('L','openurl.library') THEN
  61.            CALL ADDLIB('openurl.library',3,-66)
  62.  
  63.            IF url="" THEN DO
  64.               SAY "Usage:"
  65.               SAY "  rx OpenURL <url>"
  66.               EXIT
  67.            END
  68.  
  69.            SAY "Opening URL in new browser window..."
  70.            success = OpenURL(url, SHOW, TOFRONT, NEWWIN, LAUNCH)
  71.  
  72.            IF success=0 THEN
  73.               SAY "Failed to open URL"
  74.            ELSE
  75.               SAY "Succeeded in opening URL"
  76.  
  77.            SAY "Launching OpenURL prefs program..."
  78.            success = OpenURLPrefs()
  79.  
  80.            IF success=0 THEN
  81.               SAY "Failed to launch OpenURL prefs program"
  82.            ELSE
  83.               SAY "Succeeded in launching OpenURL prefs program"
  84.  
  85.         EXIT
  86. openurl.library/URL_OpenA                     openurl.library/URL_OpenA
  87.  
  88.      NAME
  89.         URL_OpenA - Open an URL by sending it to a browser.      (V1)
  90.  
  91.      SYNOPSIS
  92.         success = URL_OpenA(url, tags)
  93.         d0                  a0   a1
  94.  
  95.         BOOL URL_OpenA(STRPTR, struct TagItem *);
  96.  
  97.         success = URL_Open(url, firsttag, ...)
  98.  
  99.      FUNCTION
  100.         Open URL, optionally uniconify browser, bringing its screen to
  101.         front, opening the URL in a new browser window and launching the
  102.         browser if it isn't running.
  103.  
  104.      INPUTS
  105.         url - The URL.
  106.         tags - see below for allowed ones.
  107.  
  108.      TAGS
  109.         The defaults shown next to each tag is the "default default", 
  110.         users may configure their own defaults starting with V2.
  111.  
  112.         URL_Show (BOOL) - show/uniconify browser, default TRUE.
  113.  
  114.         URL_BringToFront (BOOL) - bring browser to front, default TRUE.
  115.  
  116.         URL_NewWindow (BOOL) - open URL in new window, default FALSE.
  117.  
  118.         URL_Launch (BOOL) - launch browser when not running, default 
  119.                             TRUE.
  120.  
  121.      RETURNS
  122.         Returns TRUE for success, and FALSE for failure to contact/start
  123.         any browser.
  124.  
  125.      NOTES
  126.         From V2, the ARexx commands used to display URLs are sent
  127.         asynchronously, in other words, the functions returns 
  128.         immediatedly, even if the browser is slow in replying the ARexx 
  129.         message, or possibly crashed and not replying at all.
  130.  
  131.      EXAMPLE
  132.         See the included OpenURL.c.
  133.  
  134. openurl.library/URL_GetPrefs               openurl.library/URL_GetPrefs
  135.  
  136.      NAME
  137.         URL_GetPrefs - Get a copy of openurl.library preferences.  (V1)
  138.  
  139.      SYNOPSIS
  140.         prefs = URL_GetPrefs()
  141.         d0
  142.  
  143.         struct URL_Prefs *URL_GetPrefs(VOID);
  144.  
  145.      FUNCTION
  146.         Get a copy of openurl.library preferences. Call this to get 
  147.         your own copy of the preferences to read from. When you're 
  148.         done, have URL_FreePrefs() free it.
  149.  
  150.      INPUTS
  151.         none
  152.  
  153.      RETURNS
  154.         Returns a valid pointer to a URL_Prefs structure, or NULL for 
  155.         failure.
  156.  
  157.      NOTES
  158.         Remember to check the version number of the structure you get in
  159.         return!  Do not make any assumptions about the structure if it
  160.         doesn't match the version that you handle.
  161.  
  162.      SEE ALSO
  163.         URL_FreePrefs() URL_SetPrefs()
  164.  
  165. openurl.library/URL_FreePrefs             openurl.library/URL_FreePrefs
  166.  
  167.      NAME
  168.         URL_FreePrefs - Free a copy of openurl.library preferences. (V1)
  169.  
  170.      SYNOPSIS
  171.         URL_FreePrefs(prefs)
  172.                       a0
  173.  
  174.         VOID URL_FreePrefs(struct URL_Prefs *);
  175.  
  176.      FUNCTION
  177.         Free a copy of openurl.library preferences.  Call this when you're
  178.         done with the prefs that URL_GetPrefs() gave you.
  179.  
  180.      INPUTS
  181.         prefs - pointer to URL_Prefs structure
  182.  
  183.      SEE ALSO
  184.         URL_GetPrefs()
  185.  
  186. openurl.library/URL_SetPrefs               openurl.library/URL_SetPrefs
  187.  
  188.      NAME
  189.         URL_SetPrefs - Set openurl.library preferences.            (V1)
  190.  
  191.      SYNOPSIS
  192.         success = URL_SetPrefs(prefs, permanent)
  193.         d0                     a0     d0
  194.  
  195.         BOOL URL_SetPrefs(struct URL_Prefs *, BOOL);
  196.  
  197.      FUNCTION
  198.         Set openurl.library preferences.  Call this when the user has
  199.         finished editing the preferences and pressed Save or Use in your
  200.         preference program.
  201.  
  202.      INPUTS
  203.         prefs - pointer to URL_Prefs structure
  204.         permanent - boolean, TRUE for save to disk (ENVARC), FALSE for
  205.                     save to ram (ENV)
  206.  
  207.      RETURNS
  208.         TRUE for success, FALSE for error.
  209.  
  210.      NOTES
  211.         The whole structure including linked list is copied, so you must
  212.         free your own copy.
  213.  
  214.      SEE ALSO
  215.         URL_GetPrefs()
  216.  
  217. openurl.library/URL_GetDefaultPrefs openurl.library/URL_GetDefaultPrefs
  218.  
  219.      NAME
  220.         URL_GetDefaultPrefs - Get a copy of the default openurl.library 
  221.         preferences. (V2)
  222.  
  223.      SYNOPSIS
  224.         prefs = URL_GetDefaultPrefs()
  225.         d0
  226.  
  227.         struct URL_Prefs *URL_GetDefaultPrefs(VOID);
  228.  
  229.      FUNCTION
  230.         Get a copy of the default openurl.library preferences. Call 
  231.         this to get your own copy of the preferences to read from.  
  232.         When you're done, have URL_FreePrefs() free it.
  233.  
  234.      INPUTS
  235.         none
  236.  
  237.      RETURNS
  238.         Returns a valid pointer to a URL_Prefs structure, or NULL for 
  239.         failure.
  240.  
  241.      NOTES
  242.         Remember to check the version number of the structure you get in
  243.         return!  Do not make any assumptions about the structure if it
  244.         doesn't match the version that you handle.
  245.  
  246.      SEE ALSO
  247.         URL_FreePrefs() URL_SetPrefs()
  248.  
  249. openurl.library/URL_LaunchPrefsApp   openurl.library/URL_LaunchPrefsApp
  250.  
  251.      NAME
  252.         URL_LaunchPrefsApp - Launch openurl.library prefs program (V3)
  253.  
  254.      SYNOPSIS
  255.         success = URL_LaunchPrefsApp()
  256.         d0
  257.  
  258.         BOOL URL_LaunchPrefsApp(VOID)
  259.  
  260.      FUNCTION
  261.         Use this function if you want to offer a way to configure 
  262.         openurl.library from inside your application.
  263.  
  264.      INPUTS
  265.         none
  266.  
  267.      RETURNS
  268.         TRUE for success, FALSE for error.
  269.  
  270.